feat: Add debug mode to one-shot commands by xalelax · Pull Request #631 · pasteurlabs/tesseract-core

xalelax · 2026-06-26T14:17:49Z

Relevant issue or PR

Debugging Tesseracts was limited to the serve command; this extends it to tesseract run ... commands. For those, the runtime waits for a debugger to attach, so that everything after it is in principle observable. That includes, for instance, tesseract_api.py import-time stuff.

Description of changes

Refactored existing logic for the serve debugger into a common function.
Added --debug arg to run; piped that in a few places
Added a small paragraph to the docs

Some questions still open:

I silenced the warnings that can be seen in the video with cea6bd3; should be a reasonable choice given that very seldom one needs to go down in the call stack until stdlib stuff is reached, but we could also force python to use non-freezed versions of stdlib (-Xfrozen_modules=off).
The port debugpy listens to changes every time by default, unless host networking is used. I think it's not too bad, and the manual bit of inserting that port into the launch config can be ameliorated with multiple strategies (like having "port": "${input:debugPort}" in the launch config, and a corresponding input defined).

Testing done

(warnings were still there because this video is before cea6bd3)

Recording.2026-06-26.181450.mp4

Here's a more refined version, with the edits described in the previous section

Recording.2026-06-26.225216.mp4

codecov · 2026-06-26T14:20:24Z

Codecov Report

❌ Patch coverage is 30.43478% with 16 lines in your changes missing coverage. Please review.
✅ Project coverage is 77.84%. Comparing base (2b7ac30) to head (5241671).

Files with missing lines	Patch %	Lines
tesseract_core/runtime/cli.py	7.14%	13 Missing ⚠️
tesseract_core/sdk/engine.py	66.66%	2 Missing and 1 partial ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main     #631      +/-   ##
==========================================
- Coverage   77.95%   77.84%   -0.11%     
==========================================
  Files          39       39              
  Lines        4635     4654      +19     
  Branches      754      759       +5     
==========================================
+ Hits         3613     3623      +10     
- Misses        716      724       +8     
- Partials      306      307       +1

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

PasteurBot · 2026-06-26T14:25:15Z

Benchmark Results

Benchmarks use a no-op Tesseract to measure pure framework overhead.

🚀 0 faster, ⚠️ 0 slower, ✅ 36 unchanged

✅ No significant performance changes detected.

Full results

Benchmark	Baseline	Current	Change	Status
`api/apply_1,000`	0.387ms	0.392ms	+1.3%	✅
`api/apply_100,000`	0.389ms	0.402ms	+3.2%	✅
`api/apply_10,000,000`	0.388ms	0.402ms	+3.8%	✅
`cli/apply_1,000`	1549.433ms	1535.443ms	-0.9%	✅
`cli/apply_100,000`	1531.974ms	1547.593ms	+1.0%	✅
`cli/apply_10,000,000`	1618.735ms	1598.840ms	-1.2%	✅
`decoding/base64_1,000`	0.027ms	0.027ms	+0.5%	✅
`decoding/base64_100,000`	0.758ms	0.765ms	+0.9%	✅
`decoding/base64_10,000,000`	110.096ms	111.076ms	+0.9%	✅
`decoding/binref_1,000`	0.164ms	0.166ms	+1.3%	✅
`decoding/binref_100,000`	0.257ms	0.261ms	+1.8%	✅
`decoding/binref_10,000,000`	20.387ms	20.352ms	-0.2%	✅
`decoding/json_1,000`	0.089ms	0.090ms	+0.5%	✅
`decoding/json_100,000`	8.330ms	8.359ms	+0.3%	✅
`decoding/json_10,000,000`	1046.083ms	1045.155ms	-0.1%	✅
`encoding/base64_1,000`	0.034ms	0.034ms	+0.1%	✅
`encoding/base64_100,000`	0.210ms	0.194ms	-7.8%	✅
`encoding/base64_10,000,000`	47.231ms	47.858ms	+1.3%	✅
`encoding/binref_1,000`	0.244ms	0.235ms	-3.4%	✅
`encoding/binref_100,000`	0.417ms	0.401ms	-4.0%	✅
`encoding/binref_10,000,000`	22.902ms	22.589ms	-1.4%	✅
`encoding/json_1,000`	0.119ms	0.122ms	+2.4%	✅
`encoding/json_100,000`	10.786ms	11.113ms	+3.0%	✅
`encoding/json_10,000,000`	1234.002ms	1257.782ms	+1.9%	✅
`http/apply_1,000`	2.860ms	2.855ms	-0.2%	✅
`http/apply_100,000`	8.033ms	8.566ms	+6.6%	✅
`http/apply_10,000,000`	789.644ms	778.800ms	-1.4%	✅
`roundtrip/base64_1,000`	0.069ms	0.070ms	+0.8%	✅
`roundtrip/base64_100,000`	1.131ms	1.133ms	+0.2%	✅
`roundtrip/base64_10,000,000`	159.411ms	158.934ms	-0.3%	✅
`roundtrip/binref_1,000`	0.409ms	0.420ms	+2.8%	✅
`roundtrip/binref_100,000`	0.658ms	0.672ms	+2.1%	✅
`roundtrip/binref_10,000,000`	43.779ms	44.382ms	+1.4%	✅
`roundtrip/json_1,000`	0.217ms	0.221ms	+1.6%	✅
`roundtrip/json_100,000`	18.002ms	17.987ms	-0.1%	✅
`roundtrip/json_10,000,000`	2268.246ms	2296.109ms	+1.2%	✅

Runner: Linux 6.17.0-1018-azure x86_64

dionhaefner · 2026-06-29T11:45:47Z

    return "\n".join(docstring)


+def _maybe_start_debugger(wait_for_client: bool, port: int = 5678) -> None:


I think the logic here would turn out cleaner if this was just _start_debugger (or more accurately _start_debug_server), and you check for config.debug in the caller.

dionhaefner · 2026-06-29T11:50:55Z

I wonder if there's a good way to test this on the runtime side, too. Maybe run in debug mode with a trivial Tesseract and ensure it only exits after a fake debugger is attached?

dionhaefner

Great feature and implementation, thanks!

feat: Add debug mode to one-shot commands

d55b63c

Silence warning

cea6bd3

xalelax marked this pull request as ready for review June 26, 2026 20:59

xalelax requested review from apaleyes, dionhaefner and jpbrodrick89 as code owners June 26, 2026 20:59

Merge branch 'main' into ale/add-debugpy-to-tesseract-run

5241671

dionhaefner reviewed Jun 29, 2026

View reviewed changes

dionhaefner approved these changes Jun 29, 2026

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

feat: Add debug mode to one-shot commands#631

feat: Add debug mode to one-shot commands#631
xalelax wants to merge 3 commits into
mainfrom
ale/add-debugpy-to-tesseract-run

xalelax commented Jun 26, 2026 •

edited

Loading

Uh oh!

codecov Bot commented Jun 26, 2026 •

edited

Loading

Uh oh!

PasteurBot commented Jun 26, 2026 •

edited

Loading

Uh oh!

dionhaefner Jun 29, 2026

Uh oh!

dionhaefner Jun 29, 2026

Uh oh!

dionhaefner left a comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

		return "\n".join(docstring)


		def _maybe_start_debugger(wait_for_client: bool, port: int = 5678) -> None:

Uh oh!

Conversation

xalelax commented Jun 26, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Relevant issue or PR

Description of changes

Testing done

Uh oh!

codecov Bot commented Jun 26, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

PasteurBot commented Jun 26, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Benchmark Results

Uh oh!

dionhaefner Jun 29, 2026

Choose a reason for hiding this comment

Uh oh!

dionhaefner Jun 29, 2026

Choose a reason for hiding this comment

Uh oh!

dionhaefner left a comment

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

xalelax commented Jun 26, 2026 •

edited

Loading

codecov Bot commented Jun 26, 2026 •

edited

Loading

PasteurBot commented Jun 26, 2026 •

edited

Loading